JBoss Community Archive (Read Only)

RHQ 4.5

Building a Remote WS Client

Web Service Remote Clients

Deploying the server-side services

See Web Services Installation for more details, but to enable the Remote API as Web services the following steps can be taken:

  1. Shut down the RHQ Server

  2. cd to RHQ/jbossas/server/default/deploy

  3. rename jbossws.sar.rej to jboss.sar

  4. restart the RHQ Server

The RHQ Server does not deploy the service endpoints by default because of the additional server startup time that is incurred.

Generating the Client Side Artifacts

Due to the nature of the Web Service client usage model, it is not feasible for us to cover or document ALL possible WS client usage patterns and generated types. Each WSDL consumption toolkit necessarily creates platform specific types and property/field usage patterns that are out of scope for this discussion. We will provide examples of the usage patterns developed for JBossWS clients, which you would do well to follow and adapt appropriately for your chosen wsdl consumption platform/language.

Using the WSDL now accessible via the RHQ Server you'll need to generate the client-side artifacts your client application will use to make Web Service requests. This is language, and tool, dependent. I'd like to build up several examples of how this is done (feel free to submit if you've got info to share) but to start I'll work with a Java client built with JBossWS.

RHQ 2.3 deploys its web services using JBossAS 4.2.3 and JBossWS 3.1.1.GA.

Java Client / JBossWS

To consume the WSDL and generate client-side artifacts using JBossWS you need to run the wsconsume utility provided with JBossWS. To run this utility you must have JBossWS 1 installed into a JBossAS 2. You can do this following the instructions 3 or you can leverage the fact that the RHQ Server is a JBossAS and already has JBossWS installed.

1 Download and unzip JBossWS 3.1.1.GA from http://jboss.org/jbossws/downloads/
2 Download and unzip JBossAS 4.2.3.GA from http://jboss.org/jbossas/downloads/
3 http://www.jboss.org/community/wiki/JBossWS-Installation

To run wsconsume the RHQ Server must be running and have the web services deployed (see above).

To run wsconsume from your RHQ Server installation: 

cd RHQ/jbossas/bin
./wsconsume.sh --package=org.jopr.ws \
               --output=/home/me/myjoprclient/src/main/java \
               --target=2.1 http://<Host>:<Port>/rhq-rhq-enterprise-server-ejb3/WebservicesManagerBean?wsdl

Using the generated types / JBossWS

You should now have generated types, in /home/me/myjoprclient/src/main/java for all the objects types needed to talk to the RHQ instance. The following pattern should help when using the Web Service interface:

  1. Create your (language specific) proxy.

    1. Java 

      1. ...
WebservicesManagerBeanService webservice = new WebservicesManagerBeanService();
WebservicesRemote WEBSERVICE_PROXY = webservice.getWebservicesManagerBeanPort();
...

  2. Login to the RHQ server using login(username,password) off your WS proxy and save your subject reference for subsequent requests.

    1. Java 

      1.  Subject subject = WEBSERVICE_PROXY.login("(jopr_user)", "(jopr_password)");

  3. Locate the functional area that you want to work with by browsing functionality breakdown by SLSB and begin building types and sending requests.

    1. The link above shows how remote functionality for RHQ is grouped by Stateless Session Bean, but for WS clients, all functionality is available directly off the WS proxy object. For example, you would like to find which roles are assigned to a particular user:

      1. Browsing functionality by SLSB you would discover that the RoleManagerBean exists and that the method getSubjectAssignedRoles is available for remotely requesting attached roles for a given user on the RHQ server.

      2. The next step would be to make that call from your WS proxy object.

        Due to the disconnected nature of the web service requests, the first argument of most WS calls requires a Subject(generated type) instance, representing your authenticated user, that 'subject' is used to make an authenticate request to do some desired action on the RHQ server on your behalf. Make sure that the authenticated user that makes the request has the correct permissions needed on the server side to complete the requested action.

Running with the right classpath / JBossWS

For java clients leveraging JAXWS and JAXB for client communication, like JBossWS, you should take care in setting up your classpath to run your client code. The Sun JDKs, bundle versions of JAXWS and JAXB in the JDK, but the versions of these components leveraged by JBossWS have been enhanced with bug fixes that occurred since the release of the JDK you may be using. To this end, JBossWS provides wsrunclient.sh/bat scripts that correctly sets the classpath and endorsed components to use JAXWS for Web Service clients. **See RHQ/jbossas/bin/wsrunclient.sh/bat for details. If you elect not to use the wsrunclient scripts provided by JBossWS then you should mimic the runtime classpath setup for runtime environment appropriately for optimal results.

A few differences to note for WS clients

RHQ uses JBossWS leveraging JAXWS/JAXB to build the Web Service interface(WSDL). JAXB has a few limitations when describing/serializing complicated object models to XML Schema elements. To this end, some of the objects returned may not parallel exactly the objects that are described in the SLSB documentation. The following caveats should be noted for WS clients.

References causing cyclic references will be unavailable off the returned object alone.

Essentially by providing a Web Service interface for RHQ, we are exposing an XML representation of parts of the RHQ object hierarchy. Object hierarchies are complex and frequently contain circular references that a JVM or ORM is familiar with resolving but JBossWS/JAXB has no way to resolve at this time. Ex. a reference to a parent resource may not be available from a child as the parent will then subsequently reference the same child creating a cycle. In such cases a separate request for the parent resource(by id) may be necessary.

(Insert next)

Further Examples

For more Web Service client examples.

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-12 13:19:51 UTC, last content change 2009-11-09 15:05:39 UTC.